home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Acl.java < prev    next >
Text File  |  1998-10-14  |  9KB  |  244 lines
  1. /*
  2.  * @(#)Acl.java    1.13 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security.acl;
  16.  
  17. import java.util.Enumeration;
  18. import java.security.Principal;
  19.  
  20. /**
  21.  * Interface representing an Access Control List (ACL).  An Access
  22.  * Control List is a data structure used to guard access to
  23.  * resources.<p>
  24.  *
  25.  * An ACL can be thought of as a data structure with multiple ACL
  26.  * entries.  Each ACL entry, of interface type AclEntry, contains a
  27.  * set of permissions associated with a particular principal. (A
  28.  * principal represents an entity such as an individual user or a
  29.  * group). Additionally, each ACL entry is specified as being either
  30.  * positive or negative. If positive, the permissions are to be
  31.  * granted to the associated principal. If negative, the permissions
  32.  * are to be denied.<p>
  33.  *
  34.  * The ACL Entries in each ACL observe the following rules:<p>
  35.  *
  36.  * <ul> <li>Each principal can have at most one positive ACL entry and
  37.  * one negative entry; that is, multiple positive or negative ACL
  38.  * entries are not allowed for any principal.  Each entry specifies
  39.  * the set of permissions that are to be granted (if positive) or
  40.  * denied (if negative). <p>
  41.  * 
  42.  * <li>If there is no entry for a particular principal, then the
  43.  * principal is considered to have a null (empty) permission set.<p>
  44.  *
  45.  * <li>If there is a positive entry that grants a principal a
  46.  * particular permission, and a negative entry that denies the
  47.  * principal the same permission, the result is as though the
  48.  * permission was never granted or denied. <p>
  49.  *
  50.  * <li>Individual permissions always override permissions of the
  51.  * group(s) to which the individual belongs. That is, individual
  52.  * negative permissions (specific denial of permissions) override the
  53.  * groups' positive permissions. And individual positive permissions
  54.  * override the groups' negative permissions.<p>
  55.  *
  56.  * </ul>
  57.  *
  58.  * The <code> java.security.acl </code> package provides the
  59.  * interfaces to the ACL and related data structures (ACL entries,
  60.  * groups, permissions, etc.), and the <code> sun.security.acl </code>
  61.  * classes provide a default implementation of the interfaces. For
  62.  * example, <code> java.security.acl.Acl </code> provides the
  63.  * interface to an ACL and the <code> sun.security.acl.AclImpl </code>
  64.  * class provides the default implementation of the interface.<p>
  65.  * 
  66.  * The <code> java.security.acl.Acl </code> interface extends the
  67.  * <code> java.security.acl.Owner </code> interface. The Owner
  68.  * interface is used to maintain a list of owners for each ACL.  Only
  69.  * owners are allowed to modify an ACL. For example, only an owner can
  70.  * call the ACL's <code>addEntry</code> method to add a new ACL entry 
  71.  * to the ACL.
  72.  * 
  73.  * @see java.security.acl.AclEntry
  74.  * @see java.security.acl.Owner
  75.  * @see java.security.acl.Acl#getPermissions
  76.  * 
  77.  * @version 1.13, 98/10/05
  78.  * @author Satish Dharmaraj 
  79.  */
  80.  
  81. public interface Acl extends Owner {
  82.  
  83.     /**
  84.      * Sets the name of this ACL.
  85.      *
  86.      * @param caller the principal invoking this method. It must be an
  87.      * owner of this ACL.
  88.      *
  89.      * @param name the name to be given to this ACL.
  90.      *
  91.      * @exception NotOwnerException if the caller principal
  92.      * is not an owner of this ACL.  
  93.      */
  94.     public void setName(Principal caller, String name)
  95.       throws NotOwnerException;
  96.  
  97.     /**
  98.      * Returns the name of this ACL. 
  99.      *
  100.      * @return the name of this ACL.
  101.      */
  102.     public String getName();
  103.  
  104.     /**
  105.      * Adds an ACL entry to this ACL. An entry associates a principal
  106.      * (e.g., an individual or a group) with a set of
  107.      * permissions. Each principal can have at most one positive ACL
  108.      * entry (specifying permissions to be granted to the principal)
  109.      * and one negative ACL entry (specifying permissions to be
  110.      * denied). If there is already an ACL entry of the same type
  111.      * (negative or positive) already in the ACL, false is returned.
  112.      * 
  113.      * @param caller the principal invoking this method. It must be an
  114.      * owner of this ACL.
  115.      *
  116.      * @param entry the ACL entry to be added to this ACL.
  117.      *
  118.      * @return true on success, false if an entry of the same type
  119.      * (positive or negative) for the same principal is already
  120.      * present in this ACL.
  121.      *
  122.      * @exception NotOwnerException if the caller principal
  123.      *  is not an owner of this ACL.  
  124.      */
  125.     public boolean addEntry(Principal caller, AclEntry entry)
  126.       throws NotOwnerException;
  127.  
  128.     /**
  129.      * Removes an ACL entry from this ACL.
  130.      * 
  131.      * @param caller the principal invoking this method. It must be an
  132.      * owner of this ACL.
  133.      *  
  134.      * @param entry the ACL entry to be removed from this ACL.
  135.      * 
  136.      * @return true on success, false if the entry is not part of this ACL.
  137.      * 
  138.      * @exception NotOwnerException if the caller principal is not
  139.      * an owner of this Acl.
  140.      */
  141.     public boolean removeEntry(Principal caller, AclEntry entry)
  142.           throws NotOwnerException;
  143.  
  144.     /**
  145.      * Returns an enumeration for the set of allowed permissions for the 
  146.      * specified principal (representing an entity such as an individual or 
  147.      * a group). This set of allowed permissions is calculated as
  148.      * follows:<p>
  149.      *
  150.      * <ul>
  151.      *  
  152.      * <li>If there is no entry in this Access Control List for the 
  153.      * specified principal, an empty permission set is returned.<p>
  154.      * 
  155.      * <li>Otherwise, the principal's group permission sets are determined.
  156.      * (A principal can belong to one or more groups, where a group is a 
  157.      * group of principals, represented by the Group interface.)
  158.      * The group positive permission set is the union of all 
  159.      * the positive permissions of each group that the principal belongs to.
  160.      * The group negative permission set is the union of all 
  161.      * the negative permissions of each group that the principal belongs to.
  162.      * If there is a specific permission that occurs in both 
  163.      * the positive permission set and the negative permission set, 
  164.      * it is removed from both.<p>
  165.      *
  166.      * The individual positive and negative permission sets are also 
  167.      * determined. The positive permission set contains the permissions 
  168.      * specified in the positive ACL entry (if any) for the principal. 
  169.      * Similarly, the negative permission set contains the permissions
  170.      * specified in the negative ACL entry (if any) for the principal. 
  171.      * The individual positive (or negative) permission set is considered 
  172.      * to be null if there is not a positive (negative) ACL entry for the
  173.      * principal in this ACL.<p>
  174.      *
  175.      * The set of permissions granted to the principal is then calculated 
  176.      * using the simple rule that individual permissions always override 
  177.      * the group permissions. That is, the principal's individual negative
  178.      * permission set (specific denial of permissions) overrides the group 
  179.      * positive permission set, and the principal's individual positive 
  180.      * permission set overrides the group negative permission set. 
  181.      * 
  182.      * </ul>
  183.      *
  184.      * @param user the principal whose permission set is to be returned.
  185.      * 
  186.      * @return the permission set specifying the permissions the principal 
  187.      * is allowed. 
  188.      */
  189.     public Enumeration getPermissions(Principal user);
  190.  
  191.     /**
  192.      * Returns an enumeration of the entries in this ACL. Each element in 
  193.      * the enumeration is of type AclEntry.
  194.      * 
  195.      * @return an enumeration of the entries in this ACL.
  196.      */
  197.     public Enumeration entries();
  198.  
  199.     /**
  200.      * Checks whether or not the specified principal has the specified 
  201.      * permission. If it does, true is returned, otherwise false is returned.
  202.      * 
  203.      * More specifically, this method checks whether the passed permission
  204.      * is a member of the allowed permission set of the specified principal.
  205.      * The allowed permission set is determined by the same algorithm as is 
  206.      * used by the <code>getPermissions</code> method.
  207.      * 
  208.      * @param principal the principal, assumed to be a valid authenticated 
  209.      * Principal.
  210.      * 
  211.      * @param permission the permission to be checked for.
  212.      * 
  213.      * @return true if the principal has the specified permission, false 
  214.      * otherwise.
  215.      * 
  216.      * @see #getPermissions
  217.      */
  218.     public boolean checkPermission(Principal principal, Permission permission);
  219.  
  220.     /**
  221.      * Returns a string representation of the 
  222.      * ACL contents.
  223.      * 
  224.      * @return a string representation of the ACL contents.
  225.      */
  226.     public String toString();
  227. }
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.